<?php
/**
 * Copyright (c) 2008, Till Klampaeckel
 * 
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without modification,
 * are permitted provided that the following conditions are met:
 * 
 *  * Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *  * Redistributions in binary form must reproduce the above copyright notice, this
 *    list of conditions and the following disclaimer in the documentation and/or
 *    other materials provided with the distribution.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * PHP Version 5
 *
 * @category Services
 * @package  Services_Plazes
 * @author   Till Klampaeckel <till@php.net>
 * @license  http://www.opensource.org/licenses/bsd-license.php The BSD License
 * @version  CVS: $Id$
 * @link     http://code.google.com/p/servicesplazes/
 */

/**
 * Services_Plazes_Adapter_Users_Exception
 */
require_once 'Services/Plazes/Adapter/Users/Exception.php';

/**
 * A class to interface the API of plazes.com.
 *
 * @category Services
 * @package  Services_Plazes
 * @author   Till Klampaeckel <till@php.net>
 * @license  http://www.opensource.org/licenses/bsd-license.php The BSD License
 * @version  Release: @package_version@
 * @link     http://code.google.com/p/servicesplazes/
 */
final class Services_Plazes_Adapter_Users extends Services_Plazes
{
    /**
     * @var $httpRequest
     */
    protected $httpRequest;
    
    /**
     * @var $endpoint
     */
    protected $endpoint;

    /**
     * __construct
     */
    private function __construct()
    {
    }
    
    /**
     * factory
     *
     * Used to initialize Users adapter.
     *
     * @param array $params Params passed in from Services_Plazes.
     *
     * @return Services_Plazes_Adapter_Users
     * @uses Services_Plazes::setParams()
     */
    static function factory($params)
    {
        $users = new Services_Plazes_Adapter_Users;
        $users->setParams($params);
        
        return $users;
    }
    
    /**
     * getUser
     *
     * Retrieves all info about a user (by id). If you feel like it you can query
     * plazes for information which is only available to the public, but temporarily
     * removing the Basic Auth credentials from the current request.
     *
     * @param int     $id      The plazes user ID.
     * @param boolean $useAuth To authenticate, or to not authentica...
     *
     * @return array
     * @throws Services_Plazes_Adapter_Users_Exception In case the request fails.
     */
    public function getUser($id, $useAuth = true)
    {
        if ($useAuth === false) {
            $username = $this->httpRequest->_user;
            $password = $this->httpRequest->_pass;
            
            $this->httpRequest->setBasicAuth(null, null);
        }
        
        $url = $this->endpoint . '/users/' . $id . '.xml';
        try {
            $response = $this->makeRequest($url, 'GET');
        } catch (Services_Plazes_Adapter_Exception $e) {
            throw new Services_Plazes_Adapter_Users_Exception(
                $e->getMessage(),
                $e->getCode()
            );
        }
        
        if ($useAuth === false) {
            if (!empty($username)) {
                $this->httpRequest->setBasicAuth($username, $password);
            }
        }
        return $this->_parseResponse($response);
    }
    
    /**
     * getMe
     *
     * Returns all info about the (current) authenticated user.
     *
     * @return array
     */
    public function getMe()
    {
        $url      = $this->endpoint . '/me.xml';
        $response = $this->makeRequest($url, 'GET');
        
        return $this->_parseResponse($response);
    }
    
    /**
     * searchUser
     *
     * Searches plazes for arguments.
     *
     * Note: note according to the docs the query string is split at "space" and 
     * used to search all available fields in all users on plazes.
     *
     * @param string $query The search query.
     *
     * @return array
     * @see    http://www.plazes.com/api/docs#GET__users__id__xml
     */
    public function searchUser($query)
    {
        $url = $this->endpoint . '/users.xml?q=' .  urlencode($query);
       
        try {
            $response = $this->makeRequest($url, 'GET');
        } catch (Services_Plazes_Adapter_Exception $e) {
            throw new Services_Plazes_Adapter_Users_Exception(
                $e->getMessage(),
                $e->getCode()
            );
        }
        return $this->_parseResponse($response);
    }
    
    /**
     * _parseResponse
     *
     * @param string $response The response received from the API.
     *
     * @return array
     */
    private function _parseResponse($response)
    {
        $simpleXml = simplexml_load_string($response);
        return (array) $simpleXml;
    }
}
?>